<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
  "http://www.w3.org/TR/html4/loose.dtd">
<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
    <title>Quickstart guide &mdash; build.py Documentation</title>
    <link rel="stylesheet" href="../style/default.css" type="text/css">
    <link rel="stylesheet" href="../style/pygments.css" type="text/css">
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:   '../',
        VERSION:    '0.3'
      };
    </script>
    <script type="text/javascript" src="../style/jquery.js"></script>
    <script type="text/javascript" src="../style/interface.js"></script>
    <script type="text/javascript" src="../style/doctools.js"></script>
    <link rel="contents" title="Global table of contents" href="../contents.html">
    <link rel="index" title="Global index" href="../genindex.html">
    <link rel="search" title="Search" href="../search.html">
    <link rel="top" title="build.py Documentation" href="../index.html">
    <link rel="up" title="build.py Tutorial contents" href="index.html">
    <link rel="next" title="build.py Tutorial contents" href="index.html">
    <link rel="prev" title="Introduction to build.py" href="introduction.html">
    
  </head>
  <body>

    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px"><a href="../genindex.html" title="General Index" accesskey="I">index</a></li>
        <li class="right"><a href="../modindex.html" title="Global Module Index" accesskey="M">modules</a> |</li>
          <li class="right"><a href="index.html" title="build.py Tutorial contents" accesskey="N">next</a> |</li>
          <li class="right"><a href="introduction.html" title="Introduction to build.py" accesskey="P">previous</a> |</li>
        <li><a href="../index.html">build.py v0.3 Documentation</a> &raquo;</li>
          <li><a href="index.html" accesskey="U">build.py Tutorial contents</a> &raquo;</li>
      </ul>
    </div>

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body">
            
  
  <div class="section">
<h1 id="quickstart-guide">Quickstart guide<a class="headerlink" href="#quickstart-guide" title="Permalink to this headline">¶</a></h1>
<p>In this part, you will learn how to quickly create working Buildfile and apply it to existing software.</p>
<div class="section">
<h2 id="buildfile-structure">Buildfile structure<a class="headerlink" href="#buildfile-structure" title="Permalink to this headline">¶</a></h2>
<p>As you&#8217;ve learned in the Introduction, Buildfile consists of packages and corresponding targets.
Buildfile is Python script itself - it gets invoked by main build.py executuable. Virtually, it allows
you to do everything you want. build.py can be percieved as a group of handy functions which ease making building scripts.</p>
<p>Standard Buildfile consists of two parts::</p>
<div class="highlight"><pre><span class="c"># Global declarations</span>
<span class="c"># Targets</span>
</pre></div>
<p>Global declarations section is the place for general options, like which compiler to use etc. Options are set in this manner::</p>
<div class="highlight"><pre><span class="n">Option</span><span class="p">()</span><span class="o">.</span><span class="n">compiler</span><span class="o">=</span><span class="s">&#39;g++&#39;</span>
</pre></div>
<p>Option() is a global singleton which returns an instance of a container class. It will be explained later.</p>
<p>After global declarations there&#8217;s usually place for target definitions. In build.py, targets are functions named in a specific way::</p>
<pre>def packageName_targetName()</pre>
<p>Targets are executed by command line parameters. For example::</p>
<pre>./build.py ; runs target 'build' from default package (another setting in Option() )
./build.py install ; runs target 'install' from default package
./build.py build install ; runs targets 'build' and 'install' consecutively
./build.py -p Foo ; runs target 'build' from package 'Foo'</pre>
<p>There also special functions declared in the another manner. They will be discussed later.</p>
</div>
<div class="section">
<h2 id="quickstart-example">Quickstart example<a class="headerlink" href="#quickstart-example" title="Permalink to this headline">¶</a></h2>
<p>Here goes the simple example, demonstrating basic usage of build.py.
Assume there&#8217;s one project, called HelloWorld, with corresponding file structure::</p>
<pre>HelloWorld /
        / Buildfile
        / src /
                / helloworld.cpp</pre>
<p>We want to provide seamless compilation of helloworld.cpp and systemwide installation.
Here goes the Buildfile. It will be discussed afterwards::</p>
<div class="highlight"><pre><span class="n">assign_cxx</span><span class="p">()</span>
<span class="n">Option</span><span class="p">()</span><span class="o">.</span><span class="n">default_package</span><span class="o">=</span><span class="s">&#39;HelloWorld&#39;</span>

<span class="k">def</span> <span class="nf">package_HelloWorld</span><span class="p">():</span>
   <span class="n">Option</span><span class="p">()</span><span class="o">.</span><span class="n">actual</span><span class="o">=</span><span class="s">&#39;Hello World&#39;</span>
   <span class="n">Option</span><span class="p">()</span><span class="o">.</span><span class="n">binname</span><span class="o">=</span><span class="s">&#39;helloworld&#39;</span>
   <span class="n">add_dir</span><span class="p">(</span><span class="s">&#39;source&#39;</span><span class="p">,</span><span class="s">&#39;src&#39;</span><span class="p">)</span>

<span class="k">def</span> <span class="nf">HelloWorld_build</span><span class="p">():</span>
   <span class="n">process_build</span><span class="p">()</span>

<span class="k">def</span> <span class="nf">HelloWorld_install</span><span class="p">():</span>
   <span class="n">init_install</span><span class="p">()</span>
   <span class="n">copy_bin</span><span class="p">()</span>
   <span class="n">process_install</span><span class="p">()</span>
</pre></div>
<p>At first, there are global declarations. <tt class="docutils literal"><span class="pre">assign_cxx()</span></tt> sets c++ compiler and linker (actually, only g++ is supported) and sets files with extensions .cpp .c and .cxx to be built. Virtually, <tt class="docutils literal"><span class="pre">assign_cxx()</span></tt> manipulates Option() values, like ext(list of buildable extensions), compiler(name of compiler) and linker(name of linker).</p>
<p>Next comes the explict option definition - <tt class="docutils literal"><span class="pre">default_package</span></tt>. When no package name is specified through command line interface, build.py will use <tt class="docutils literal"><span class="pre">default_package</span></tt> instead.</p>
<p><tt class="docutils literal"><span class="pre">package_HelloWorld()</span></tt> is one of special functions mentioned earlier. It doesn&#8217;t meet the &#8220;packageName_targetName()&#8221; pattern. Functions with pattern &#8220;package_packageName()&#8221; will be called at beginning of processing of particular target, i.e. you can be completely sure that <tt class="docutils literal"><span class="pre">package_HelloWorld()</span></tt> will be called <em>before</em> any call to one of HelloWorld targets.</p>
<p>These type of function usually contain package-wide definitions, like directories of source, data, full package name and so on. In this example, <tt class="docutils literal"><span class="pre">actual</span></tt> means full package name (suitable to be presented to user) and <tt class="docutils literal"><span class="pre">binname</span></tt> is output binary filename (for available option list, check the API Reference). Third call, in turn, specifies the source directory - it&#8217;s &#8216;src&#8217; in our example. &#8216;source&#8217; means the <em>category</em> of given directory. When build.py starts building process, it builds all files with suitable extensions in directories marked as &#8216;source&#8217;.</p>
<p>At the end, there are two target specified - &#8216;build&#8217; and &#8216;instal&#8217;. Let&#8217;s disscuss them one by one.</p>
<p><tt class="docutils literal"><span class="pre">HelloWorld_build()</span></tt> initiates the building process by running process_build(). That&#8217;s all. build.py will take care of rest. It will compile all files marked as &#8216;source&#8217; and place resulting binary in main project directory</p>
<p><tt class="docutils literal"><span class="pre">HelloWorld_install()</span></tt> is a bit longer. It manages HelloWorld installation process. At first, there&#8217;s init_install() call. It initalizes all installation variables, classes and so on. You <em>must</em> run it before any other build.py installation routines. Next comes the copy_bin(). Without parameters, it copies binary produced in &#8216;build target&#8217; to standard, system-wide binary directory, for example /usr/bin. You can change it&#8217;s behavior by passing parameters. If you want so, consult API Reference. At the ending of all installtion routines, process_install() must be called. It finalizes all installation actions. As with init_install(), it <em>must</em> be called. If you don&#8217;t do that, your files <em>won&#8217;t</em> be installed at all!</p>
<p>That&#8217;s all of this Buildfile. If you run build.py in project&#8217;s directory, you can see that building and installing are acually happening. So, your first Buildfile is done!</p>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sidebar">
        <div class="sidebarwrapper">
          
            <h3>Table Of Contents</h3>
            <ul>
<li><a class="reference" href="">Quickstart guide</a><ul>
<li><a class="reference" href="#buildfile-structure">Buildfile structure</a></li>
<li><a class="reference" href="#quickstart-example">Quickstart example</a></li>
</ul>
</li>
</ul>

          
            <h4>Previous topic</h4>
            <p class="topless"><a href="introduction.html" title="previous chapter">Introduction to build.py</a></p>
            <h4>Next topic</h4>
            <p class="topless"><a href="index.html" title="next chapter">build.py Tutorial contents</a></p>
          
            <h3>This Page</h3>
            <ul class="this-page-menu">
            
              <li><a href="../_sources/tutorial/quickstart.txt">Show Source</a></li>
            
            </ul>
          
          
          
        </div>
      </div>
      <div class="clearer"></div>
    </div>

    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px"><a href="../genindex.html" title="General Index" accesskey="I">index</a></li>
        <li class="right"><a href="../modindex.html" title="Global Module Index" accesskey="M">modules</a> |</li>
          <li class="right"><a href="index.html" title="build.py Tutorial contents" accesskey="N">next</a> |</li>
          <li class="right"><a href="introduction.html" title="Introduction to build.py" accesskey="P">previous</a> |</li>
        <li><a href="../index.html">build.py v0.3 Documentation</a> &raquo;</li>
          <li><a href="index.html" accesskey="U">build.py Tutorial contents</a> &raquo;</li>
      </ul>
    </div>

    <div class="footer">
      &copy; Copyright 2008, Michal Hordecki.
      Last updated on Feb 10, 2008.
    </div>
  </body>
</html>